<h1>Getting started</h1>
<section>
      <a name="installing"></a>
      <h2>Installing Melpa</h2>

      <p>To use the MELPA repository, you'll need an Emacs with
        <code>package.el</code> and TLS support, ie. Emacs 24.1 or
        greater. To test TLS support you can visit a HTTPS URL, for
        example with <code>M-x eww RET https://wikipedia.org RET</code>.
      </p>

      <p>
        Consider using Emacs 26.3 or greater; otherwise you will have
        to add a kludge to work around a bug described in
        <a href="#knownIssues">Known Issues</a> below.
      </p>

      <p>
        Enable installation of packages from MELPA by adding an entry
        to <code>package-archives</code> after <code>(require
        'package)</code> and before the call
        to <code>package-initialize</code> in
        your <code>init.el</code> or <code>.emacs</code> file:
      </p>

      <pre><code>(require 'package)
(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)
;; Comment/uncomment this line to enable MELPA Stable if desired.  See `package-archive-priorities`
;; and `package-pinned-packages`. Most users will not need or want to do this.
;;(add-to-list 'package-archives '("melpa-stable" . "https://stable.melpa.org/packages/") t)
(package-initialize)</code></pre>

      <p>
        Note that you'll need to run <code>M-x package-refresh-contents</code> or
        <code>M-x package-list-packages</code> to ensure that Emacs has fetched
        the MELPA package list before you can install packages with
        <code>M-x package-install</code> or similar.
      </p>

      <h3>Installing Melpa Stable</h2>

      <p>
        To use the <a href="https://stable.melpa.org" title="MELPA Stable">
          stable package repository</a> instead of the default
        “bleeding-edge” repository, use this instead
        of <code>"melpa"</code>:
      </p>

      <pre><code>(add-to-list 'package-archives
             '("melpa-stable" . "https://stable.melpa.org/packages/") t)</code></pre>

      <h3>Installing a package</h2>

      <p>
        To install a package run <code>M-x package-install</code>.
        See <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Package-Installation.html">
        Package Installation</a> for details about that and
        <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Packages.html">
        Emacs Lisp Packages</a> for even more information about Emacs'
        package manager.
      </p>

      <h3>Customizations</h3>
      <p>
        What if you only want some of your packages to be installed
        from MELPA, and the rest from Marmalade or elsewhere?
      </p>
      <p>
        In Emacs 24.4 and later, <code>package-pinned-packages</code>
        allows you to exclude or include versions according to their
        source. For users using older versions of Emacs, we provide
        a <code>package-filter.el</code> package (available in MELPA)
        that will allow you to enable only certain packages or exclude
        certain packages.  You can install the package manually by
        pasting this into your <code>*scratch*</code> buffer and
        evaluating it.
      </p>
      <pre><code>(progn
  (switch-to-buffer
    (url-retrieve-synchronously
      "https://raw.github.com/melpa/package-filter/master/package-filter.el"))
  (package-install-from-buffer  (package-buffer-info) 'single))</code></pre>

      <p>You can then customize two variables:</p>
      <dl>
        <dt><code>package-archive-enable-alist</code></dt>
        <dd>
          <p>
            Optional Alist of enabled packages used
            by <code>package-filter</code>. The format
            is <code>(ARCHIVE . PACKAGE ...)</code>,
            where <code>ARCHIVE</code> is a string matching an archive
            name in<code>package-archives</code>, <code>PACKAGE</code>
            is a symbol of a package in <code>ARCHIVE</code> to
            enable.
          </p>
          <p>
            If no <code>ARCHIVE</code> exists in the alist, all
            packages are enabled.
          </p>
        </dd>
        <dt><code>package-archive-exclude-alist</code></dt>
        <dd>
          <p>
            Alist of packages excluded by <code>package-filter</code>.
            The format is <code>(ARCHIVE . PACKAGE ...)</code>, where
            <code>ARCHIVE</code> is a string matching an archive name
            in <code>package-archives</code>, <code>PACKAGE</code> is
            a symbol of a package in that archive to exclude.</p>
          <p>
            Any specified package is excluded regardless of the value
            of <code>package-archive-enable-alist</code>
          </p>
        </dd>
      </dl>
    </section>
    <section>
      <h2 id="knownIssues">Known Issues</h2>
      <h3>Failed to download ‘MELPA’ archive</h3>
      <p>This occasionally happens when using Emacs &#60;= 26.2
        with Gnutls &#62;= 3.6.  The recommended fix is to update to
        Emacs 26.3 or greater.  Alternatively you can disable TLS1.3
        by adding the following setting early in your init file.  For
        more information
        see <a href="https://debbugs.gnu.org/cgi/bugreport.cgi?bug=34341">Emacs
        bug#34341</a>.
      </p>
      <pre><code>(setq gnutls-algorithm-priority "NORMAL:-VERS-TLS1.3")</code></pre>

      <h3>Dependency order is reversed</h3>
      <p>
        There is a small bug in Emacs 24’s <code>package.el</code> such
        that the dependency order comes out backwards. The problem is
        patched by some <em>advice</em>.
      </p>

      <pre><code>(defadvice package-compute-transaction
    (around package-compute-transaction-fix activate)
  "Fix order of requirements."
  (let ((package-list (ad-get-arg 0)))
    (let (package-list)
      (ad-set-args 0 (list nil  (ad-get-arg 1)))
      ad-do-it)
    (dolist (elt (nreverse ad-return-value))
      (setq package-list (cons elt (delq elt package-list))))
    (setq ad-return-value package-list)))</code></pre>
    </section>
    <section>
      <a name="updating"></a>
      <h2>Updating Packages</h2>
      <p>
        After running <code>package-list-packages</code>,
        type <em>U</em> (mark Upgradable packages) and then <em>x</em>
        (eXecute the installs and deletions). When it’s done
        installing all the packages it will ask if you want to delete
        the obsolete packages and so you can hit <em>y</em> (Yes).
      </p>
      <p>
        If you run into a problem installing or upgrading, you may
        need to go into your <code>~/.emacs.d/elpa/</code> directory
        and delete packages that are installed multiple times. This
        can happen when the install times out.
      </p>
      <a name="adding"></a>
      <h2>Adding a Package</h2>
      <p>
        In so many words, fork the project's source tree and create a
        pull request with a recipe for your package.
        The <a href="https://github.com/melpa/melpa/blob/master/README.md">README.md</a>
        file on GitHub has more details.
      </p>
      <a name="development"></a>
      <h2>Development</h2>
      <p><a href="https://github.com/melpa/melpa">https://github.com/melpa/melpa</a></p>
      <p>
        Contributions are welcome. Currently, the builder supports
        packages using Git, Mercurial, and EmacsWiki (deprecated
        due to security concerns). Support for Bazaar, CVS, Darcs,
        Fossil and Subversion has been removed due to very limited
        use.
      </p>
    </section>
